home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 November / Macworld (1999-11).dmg / Updaters / WhiteCap 3.0.4 / WhiteCap Source.sit / WhiteCap Source / SJ SDK / VisFrameworkMain.c < prev    next >
C/C++ Source or Header  |  1999-08-11  |  13KB  |  337 lines
  1.  
  2. //===============================================================================
  3. //-------------------------------------------------------------------------------
  4. //                               Visual Framework Plug-in
  5. //                                version 1.0.0
  6. //                                Mike Wright
  7. //                                darwin@mbay.net
  8. //
  9. //  This is a sample module that is designed to simplify the writing of a
  10. //    visual plugin for SoundJam. It includes the code needed to register the 
  11. //    plugin with the app, as well as the code for the dispatching of incoming 
  12. //    messages from SoundJam to the appropriate handler routines.
  13. //
  14. //    The purpose of this code is to help clarify how a visual plugin module 
  15. //    should interact with SoundJam, not to teach how to create graphic displays,
  16. //    nor how to process sound data.
  17. //
  18. //    There are also message-handler functions for each of the possible messages.
  19. //    These functions are commented to make it easier to understand what kinds of
  20. //    tasks they are expected to carry out.
  21. //
  22. //    A few of the functions have been filled out with enough code to produce a
  23. //    plugin that actually does something--but not much. This plugin simply
  24. //    does some very basic processing of a portion of the spectrum data
  25. //    in order to produce some simple visual effects.
  26. //
  27. //    The handling of a pop-up menu, which comes up when the module window
  28. //    is clicked, is also implemented.
  29. //
  30. //    There is a global data structure, the VisHandlerData struct, which 
  31. //    contains the data which the plugin uses to do its jobs. This struct
  32. //    should be modified to contain the data fields that your plugin will
  33. //    need to do its job. Many of them will be the same as those in the sample
  34. //    plugin module.
  35. //
  36. //    This information is specific to visual plug-ins, but please note that a
  37. //    SoundJam plugin container may contain multiple plug-ins. In main(), when
  38. //    registering the plug-n with SoundJam, the visual plugin passes info back
  39. //    by way of the u.registerVisualPluginMessage element of the 
  40. //    PlayerMessageInfo union struct. This union also includes the following
  41. //    registration elements:
  42. //        registerPlayerPluginMessage;
  43. //        registerDSPPluginMessage;
  44. //        registerEncoderPluginMessage;
  45. //        registerSkinPluginMessage;
  46. //    See the PlayerAPI.h header file for the details of the PlayerMessageInfo
  47. //    struct.
  48. //
  49. //    Note that this sample module does not do much in the way of error checking,
  50. //    but a serious plugin should be just as careful about error checking and
  51. //    memory handling as any application.
  52. //
  53. //-------------------------------------------------------------------------------
  54. //===============================================================================
  55.  
  56.  
  57. //===============================================================================
  58. //-------------------------------------------------------------------------------
  59. //                                 VisFrameworkMain.c
  60. //
  61. //    Handles calls from SoundJam.
  62. //
  63. //    main()             handles registering our plugin module with SoundJam
  64. //    VisHandler()     retrieves our global data from the refcon and calls handlers
  65. //                 for each SoundJam message
  66. //
  67. //-------------------------------------------------------------------------------
  68. //===============================================================================
  69.  
  70.  
  71. #include "Debug.h"
  72. #include "VisFramework.h"
  73.  
  74.  
  75. //========================================================================== Functions
  76.  
  77. /* ——————————————————————————————— VisHandler —————————————————————————————————————
  78. Purpose:    This is the entry point where SoundJam will first call us. 
  79.  
  80.             We use the u.registerVisualPluginMessage of the PlayerMessageInfo 
  81.             struct to register the visual plugin with SoundJam.
  82.             
  83.             It receives the following parameters:
  84.             
  85.                 "messageInfo", which is a pointer to a union struct. Each struct
  86.                 contains fields that are required to handle the task indicated
  87.                 by the message.
  88.  
  89.                 "messageType", which is a key to the struct element of the union 
  90.                 that is contained in messageInfo.
  91.             
  92.                 "refcon", which is used to store the plugin's data structure.
  93.                 In this framework sample, the data structure type is the 
  94.                 VisHandlerData struct, which is defined in the VisFramework.h 
  95.                 header.
  96.             
  97.             The VisHandlerData struct should be redefined to hold whatever data
  98.             your plugin will need access to at each call. This will include any
  99.             data passed to the plugin via the "messageInfo" param.
  100.             
  101.             The PlayerMessageInfo struct, playerMessageInfo, is used to pass
  102.             information about the plugin to SoundJam. The fields are filled in
  103.             below according to the needs of the framework sample plugin, but you
  104.             will want to fill them in to reflect the needs of your plugin.
  105.             
  106.             The values that can be used for the options field are as follows:
  107.             
  108.               kVisualRequiresFullScreen        When the ration of the values for
  109.                                             minHeight and minWidth match the
  110.                                             ratio of height and width of the
  111.                                             screen resolution, the plugin
  112.                                             window will open to full screen.
  113.                                                 
  114.               kVisualForBuiltIn                NEVER set this bit. It is only
  115.                                             for use by the built-in visual
  116.                                             plugin (though it will probably
  117.                                             just be ignored).
  118.                                                 
  119.               kVisualIsResizeable            The plugin window will be resizable,
  120.                                             so you should be prepared to deal
  121.                                             with resize messages. HOWEVER, this
  122.                                             feature is NOT implemented in
  123.                                             SoundJam 1.0.0.
  124.                                                 
  125.               kVisualWantsIdleMessages        The plugin will receive idle messages,
  126.                                             at which time you may do whatever
  127.                                             you wish.
  128.                                                 
  129.               kVisualWantsToProcessSamples    The plugin will receive processSamples
  130.                                             messages, which will include a pointer
  131.                                             to a sound buffer which can be
  132.                                             modified by the plugin.
  133.                                             
  134.               kVisualWantsConfigure            The plugin will receive configure
  135.                                             messages. This is NOT enabled in
  136.                                             SJ 1.0.0.
  137.             
  138.               kVisualWantsAbout                The plugin will receive a message
  139.                                             telling it to display its "About"
  140.                                             information. This is NOT enabled in
  141.                                             SJ 1.0.0.
  142.             
  143.               kVisualEnabledByDefault        The plugin will be enabled when
  144.                                             SoundJam is first run, without having
  145.                                             to be turned on in the preferences.
  146. ———————————————————————————————————————————————————————————————————————————————————
  147. Arguments:    messageType - kind of message contained in messageInfo struct
  148.             messageInfo    -    pointer to a VisualPluginMessageInfo struct
  149.             refcon        -    stored plugin global data
  150. ———————————————————————————————————————————————————————————————————————————————————
  151. Returns:    noErr (always)
  152. ———————————————————————————————————————————————————————————————————————————————————
  153. */
  154. OSStatus main (OSType messageType,PluginMessageInfo *messageInfo,void *refcon)
  155. {
  156. #pragma unused (refcon)
  157.     PlayerMessageInfo    playerMessageInfo;        /* struct for passing our info back to SoundJam */
  158.     Str255                plugInName            = "\pWhiteCap";    /* put the name of your plugin here */
  159.     OSStatus            status                = noErr;
  160.     
  161.     // Look at message passed in to us.
  162.     switch (messageType)
  163.     {
  164.         case kPluginInitializeMessage:
  165.             // Fill in playerMessageInfo fields for passing to PlayerRegisterVisualPlugin()
  166.             BlockMove((Ptr)&plugInName[0],(Ptr)&playerMessageInfo.u.registerVisualPluginMessage.name[0],plugInName[0] + 1);
  167.             playerMessageInfo.u.registerVisualPluginMessage.options = kVisualEnabledByDefault | kVisualIsResizeable | kVisualWantsIdleMessages;
  168.             playerMessageInfo.u.registerVisualPluginMessage.messageVersion = kCurrentPluginMessageVersion;
  169.             playerMessageInfo.u.registerVisualPluginMessage.handler = VisHandler;
  170.             playerMessageInfo.u.registerVisualPluginMessage.registerRefcon = 0;
  171.             
  172.             // Specify timing/data information.
  173.             playerMessageInfo.u.registerVisualPluginMessage.timeBetweenDataInMS = 1;
  174.             playerMessageInfo.u.registerVisualPluginMessage.numWaveformChannels = 0;
  175.             playerMessageInfo.u.registerVisualPluginMessage.numSpectrumChannels = 2;
  176.             
  177.             // Specify our bounds constraints.
  178.             playerMessageInfo.u.registerVisualPluginMessage.minWidth = 300;        // Backward compat: put default win size here
  179.             playerMessageInfo.u.registerVisualPluginMessage.minHeight = 200;
  180.             playerMessageInfo.u.registerVisualPluginMessage.maxWidth = 640;        // Backward compat: put fullscreen size here
  181.             playerMessageInfo.u.registerVisualPluginMessage.maxHeight = 480;
  182.             
  183.             playerMessageInfo.u.registerVisualPluginMessage.windowAlignmentInBytes = 0;
  184.             
  185.             // Call the player.
  186.             status = PlayerRegisterVisualPlugin(messageInfo->u.initMessage.appCookie,
  187.                     messageInfo->u.initMessage.playerProc,&playerMessageInfo);
  188.  
  189.  
  190.         break;
  191.         
  192.         case kPluginCleanupMessage:
  193.         break;
  194.         
  195.         default:
  196.             DebugMsg("\pVisHandler: Unknown message number 1.");    
  197.             status = paramErr;
  198.         break;
  199.     }
  200.             
  201.     return status;
  202.     
  203. } /* end main */
  204.  
  205.  
  206.  
  207. /* ——————————————————————————————— VisHandler —————————————————————————————————————
  208. Purpose:    This is the function that handles messages from SoundJam.
  209.             It was registered with SoundJam in main().
  210.             
  211.             It receives the following parameters:
  212.             
  213.                 "messageInfo", which is a pointer to a union struct. Each struct
  214.                 contains fields that are required to handle the task indicated
  215.                 by the message.
  216.  
  217.                 "messageType", which is a key to the struct element of the union 
  218.                 that is contained in messageInfo.
  219.             
  220.                 "refcon", which is used to store the plugin's data structure.
  221.                 In this framework sample, the data structure type is the 
  222.                 VisHandlerData struct, which is defined in the VisFramework.h 
  223.                 header.
  224.             
  225.             The VisHandlerData struct should be redefined to hold whatever data
  226.             your plugin will need access to at each call. This will include any
  227.             data passed to the plugin via the "messageInfo" param.
  228.             
  229.             Each messageType has a matching handler that is called by VisHandler().
  230.             Future versions of SoundJam will probably add more message types.
  231. ———————————————————————————————————————————————————————————————————————————————————
  232. Arguments:    messageType -     kind of message contained in messageInfo struct
  233.             messageInfo    -    pointer to a VisualPluginMessageInfo struct
  234.             refcon        -    stored plugin global data (VisHandlerData)
  235. ———————————————————————————————————————————————————————————————————————————————————
  236. Returns:    status
  237. ———————————————————————————————————————————————————————————————————————————————————
  238. */
  239. OSStatus VisHandler (OSType messageType,VisualPluginMessageInfo *messageInfo,void *refcon)
  240. {
  241.     VisHandlerData *plugInData;
  242.     OSStatus        status;
  243.     
  244.     // Assume no errors.
  245.     status = noErr;
  246.     
  247.     // Get a grab on our plugin data.
  248.     plugInData = (VisHandlerData *)refcon;
  249.     
  250.     // See which message we're being sent and call appropriate function in VISPluginHandlers.c.
  251.     switch (messageType)
  252.     {
  253.         case kVisualPluginInitializeMessage:
  254.         status = HandleInitializeMessage(messageInfo,plugInData);        // first time in, setting up
  255.         break;
  256.         
  257.         case kVisualPluginCleanupMessage:
  258.         status = HandleCleanupMessage(plugInData);                        // shutting down, disposing allocated memory
  259.         break;
  260.         
  261.         case kVisualPluginEnableMessage:
  262.         status = HandleEnableMessage(plugInData);                        // turn on the module, allocate more memory
  263.         break;
  264.         
  265.         case kVisualPluginDisableMessage:
  266.         status = HandleDisableMessage(plugInData);                        // turn off the module, dispose memory allocated in HandleEnableMessage
  267.         break;
  268.         
  269.         case kVisualPluginShowWindowMessage:
  270.         status = HandleShowWindowMessage(messageInfo,plugInData);        // the plugin window has been made visible
  271.         break;
  272.         
  273.         case kVisualPluginHideWindowMessage:
  274.         status = HandleHideWindowMessage(plugInData);                    // the plugin window has been hidden
  275.         break;
  276.         
  277.         case kVisualPluginSetWindowMessage:
  278.         status = HandleSetWindowMessage(messageInfo,plugInData);        // the plugin window has been changed
  279.         break;
  280.         
  281.         case kVisualPluginResizeMessage:
  282.         status = HandleResizeMessage(messageInfo,plugInData);            // user has resized the plugin window
  283.         break;
  284.         
  285.         case kVisualPluginPlayMessage:
  286.         status = HandlePlayMessage(messageInfo,plugInData);                // a track has started playing
  287.         break;
  288.         
  289.         case kVisualPluginStopMessage:
  290.         status = HandleStopMessage(plugInData);                            // the current track has stopped playing
  291.         break;
  292.         
  293.         case kVisualPluginPauseMessage:
  294.         status = HandlePauseMessage(plugInData);                        // the current track has been paused
  295.         break;
  296.         
  297.         case kVisualPluginUnpauseMessage:
  298.         status = HandleUnpauseMessage(plugInData);                        // the current track has been unpaused
  299.         break;
  300.         
  301.         case kVisualPluginRenderMessage:
  302.         status = HandleRenderMessage(messageInfo,plugInData);            // render some some samples as visual
  303.         break;
  304.         
  305.         case kVisualPluginProcessSamplesMessage:
  306.         status = HandleProcessSamplesMessage(messageInfo,plugInData);    // process (modify) sound samples
  307.         break;
  308.         
  309.         case kVisualPluginFlushSamplesMessage:
  310.         status = HandleFlushSamplesMessage(plugInData);                    // dispose old sound samples and be ready for new ones
  311.         break;
  312.         
  313.         case kVisualPluginEventMessage:
  314.         status = HandleEventMessage(messageInfo,plugInData);            // handle clicks and keydowns in module window
  315.         break;
  316.         
  317.         case kVisualPluginUpdateMessage:
  318.         status = HandleUpdateMessage(plugInData);                        // handle updates of module window
  319.         break;
  320.         
  321.         case kVisualPluginIdleMessage:
  322.         status = HandleIdleMessage(plugInData);                            // the idle time you requested is available
  323.         break;
  324.         
  325.         default:
  326.         DebugMsg("\pVisHandler: Unknown message number 2.");            // What could the programmer be thinking?
  327.         status = paramErr;
  328.         break;
  329.     }
  330.     
  331. bail:
  332.             
  333.     return status;
  334.  
  335. } /* end VisHandler */
  336.  
  337.